\section{Common Usage of JEdifNMRSelection}
\label{sec:nmr_selection_examples}
This section describes a few sample scenarios and explains which combination of
command line options should be used for each.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Full TMR}
\label{subsec:fulltmr}
This example shows how to perform ``full'' TMR (triplication of all components) 
on a design. For larger designs, this may result in a TMR'd version of the 
design that does not fit in the desired chip. If this is the case, some form of 
``partial'' TMR should be used.

In this example, the design to be triplicated is
\texttt{myDesign.edf}. Both input ports and output ports are triplicated. 
The part used in this case is the Virtex II XC2V1000-FG456.

\begin{verbatim}
> java edu.byu.ece.edif.jedif.JEdifNMRSelection myDesign.jedif \
  -c myDesign.cdesc -r myDesign.rdesc --replication_type triplication \
  --nmr_inports --nmr_outports --full_nmr --part xc2v1000fg456
\end{verbatim}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Full TMR---Clock not triplicated}
Some systems are not ideal for triplicated clock lines because of resource
constraints. This example shows how to triplicate everything but the clock line.

This example is almost identical to the example in section 
\ref{subsec:fulltmr}. The \texttt{--no\_nmr\_p} option specifies that the 
top-level port named \texttt{Clk} (case-sensitive) should not be triplicated. 
The \texttt{--no\_nmr\_c} option indicates that all cells of the global clock 
buffer type \texttt{BUFG} should also not be triplicated. This prevents the 
clock line after the buffer from being triplicated and the entire circuit will 
use the same single clock.

\begin{verbatim}
> java edu.byu.ece.edif.jedif.JEdifNMRSelection myDesign.jedif \
  -c myDesign.cdesc -r myDesign.rdesc --replication_type triplication \
  --nmr_inports --nmr_outports --full_nmr --no_nmr_p Clk --no_nmr_c BUFG \
  --part xc2v1000fg456
\end{verbatim}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Full TMR---No I/O triplication}
Many FPGA applications are port-limited. This example shows how to prevent all 
inputs and outputs from being triplicated. In this example, the user must leave 
out the \texttt{--nmr\_inports} and \texttt{--nmr\_outports} parameters so that 
top level ports are not included in triplication. This example also leaves out 
the \texttt{--part} option, using the default value (a value saved as a
property in the EDIF file).

\begin{verbatim}
> java edu.byu.ece.edif.jedif.JEdifNMRSelection myDesign.jedif -c myDesign.cdesc \
  -r one_counter.rdesc --replication_type triplication --full_nmr
\end{verbatim}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Partial TMR---No I/O triplication}
This example shows a standard usage of the BL-TMR tool for partial TMR\@. In this 
case, the design is too large to fit in the targeted device when fully 
triplicated. The BL-TMR tool will triplicate as much logic as possible and 
estimate when the target chip will be fully utilized.

%This design also requires some external EDIF files that are referenced in 
%\texttt{myLargeDesign.edf} as ``black boxes.'' These external files, which are 
%located in the \texttt{externalSrcDir} directory, will be incorporated into the 
%triplicated design. Thus, the external files will not be needed with the 
%\texttt{myLargeDesign\_BL-TMR.edf} output file.

\begin{verbatim}
> java edu.byu.ece.edif.jedif.JEdifNMRSelection myLargeDesign.jedif \
  -c myLargeDesign.cdesc -r myLargeDesign.rdesc --replication_type triplication 
\end{verbatim}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Partial TMR---SCC Decomposition, custom estimation factors}
In this case, the user wishes to include parts of strongly-connected components 
(SCCs) for triplication. This example also shows how to override the default
merge and optimization factors.

\begin{verbatim}
> java java edu.byu.ece.edif.jedif.JEdifNMRSelection myLargeDesign.jedif \
  -c myLargeDesign.cdesc -r myLargeDesign.rdesc --replication_type triplication \
  --do_scc_decomposition --merge_factor 0.4 --optimization_factor 0.85
\end{verbatim}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Partial TMR---Fill 50\% of target device}
In some cases, the user may wish to use the triplicated design on the same chip 
as another design. In this example the user knows that a separate design will 
require half of the target chip. To fill as much of the left-over 50\% as 
possible, the user specifies a \texttt{--factor\_type} of \texttt{DUF} and a 
\texttt{factor\_value} of \texttt{0.5}. This will stop triplication of the 
input design when half of the target chip is utilized, according to the 
estimate made with the merge optimization factors.

\begin{verbatim}
> java edu.byu.ece.edif.jedif.JEdifNMRSelection myLargeDesign.jedif \
  -c myLargeDesign.cdesc -r myLargeDesign.rdesc --replication_type triplication \
  --factor_type DUF --factor_value 0.5
\end{verbatim}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Partial TMR---Push utilization past 100\%}
Due to the way mapping tools are implemented, the user may be able to fit more 
logic onto the target chip than estimated by the utilization tracker. The 
Xilinx \texttt{map} program, for example, does not map unrelated logic into the 
same slice until slice utilization reaches 99\%. This means that much more 
logic can be added after this point, though the place and route step will 
become increasingly more difficult for the vendor tools to perform.

With this in mind, to achieve the maximum capacity on the target chip, it may 
be necessary to specify a desired utilization factor greater than 1.0 (more 
than 100\% estimated utilization). The following example uses a device 
utilization factor of 1.5, which will stop triplication when an estimated 150\% 
of the target part is utilized.

\begin{verbatim}
> java edu.byu.ece.edif.jedif.JEdifNMRSelection myLargeDesign.jedif \
  -c myLargeDesign.cdesc -r myLargeDesign.rdesc --replication_type triplication \
  --factor_type DUF --factor_value 1.5
\end{verbatim}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Partial TMR---Use 75\% of available space on target device}
The available space utilization factor can be used to specify the amount of
space on the target device left after the unmitigated circuit is mapped. To
fill the chip up to 75\% of the left-over space, the user specifies a 
\texttt{--factor\_type} of \texttt{ASUF} and a \texttt{factor\_value} of 
\texttt{0.75}. If the original design size is estimated at using 40\% of the
target chip, this will stop triplication when 70\% ($40 + (100-40)*0.75$) of
the target chip is utilized.

\begin{verbatim}
> java edu.byu.ece.edif.jedif.JEdifNMRSelection myLargeDesign.jedif \
  -c myLargeDesign.cdesc -r myLargeDesign.rdesc --replication_type triplication \
  --factor_type ASUF --factor_value 0.75
\end{verbatim}

\subsection{Mixed TMR/DWC---TMR Persistent Section, Duplicate the Rest}
At times, it may be impossible to fit an entire triplicated design on a part.
It may still be possible to triplicate feedback sections and duplicate the rest
of the design. This can be accomplished by running JEdifNMRSelection twice. The
first run selects feedback sections for TMR and the second run selects the rest
of the design for duplication. Notice that the second run uses the
\texttt{--continue} option to indicate that the replication description
(.rdesc) file should be modified rather than overwritten. The second run also
uses the \texttt{--full\_nmr} option to select the rest of the design. This does
not override the TMR sections selected by the first run because the
\texttt{--override} option is not used.
\begin{verbatim}
> java -Xmx1G edu.byu.ece.edif.jedif.JEdifNMRSelection myDesign.jedif \
  -c myDesign.cdesc -r myDesign.rdesc --part xcv1000-5-bg560 \
  --replication_type triplication --no_nmr_feedback_output --no_nmr_feed_forward
> java -Xmx1G edu.byu.ece.edif.jedif.JEdifNMRSelection myDesign.jedif \
  -c myDesign.cdesc -r myDesign.rdesc --part xcv1000-5-bg560 \
  --replication_type duplication --continue --full_nmr
\end{verbatim}

\subsection{Triplicate Specific Instances Only}
By default, the BL-TMR tool tries to use partial replication to fill up a
device when no other options are specified. In order to suppress this behavior
and only replicate instances specified by the user, the
\texttt{--no\_partial\_nmr} option can be used. (Half-latch safe constants will
still be marked for replication in designs where half-latch removal is used, but
this behavior can be suppressed by using the \texttt{--hl\_no\_tag\_constant}
option in JEdifBuild). Specific instances should be selected for replication
using the \texttt{--nmr\_i}, \texttt{--nmr\_c}, \texttt{--nmr\_clk}, etc.
options. The following example triplicates only two instances (plus a
half-latch safe constant cell if half-latch removal was used):
\begin{verbatim}
> java edu.byu.ece.edif.jedif.JEdifNMRSelection myDesign.jedif \
  -c myDesign.cdesc -r myDesign.rdesc --replication_type triplication \
  --no_partial_nmr \
  --nmr_i synth_th1/virtexmultaccelerator_mini__1/a/multCol__13/reg_bottom_ysum/fdce,\
  synth_th1/virtexmultaccelerator_mini__1/b/multCol__1/reg_top_ysum/fdce__5 \
  --part xcv1000-5-bg560
\end{verbatim}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Using Configuration Files}
\label{using config}
Configuration files can greatly simplify the use of any of the
BL-TMR tools.  The following examples show how to create and use
configuration files.

\subsubsection{Create a Configuration File}
The following will write the current command-line arguments to the file
\texttt{myConfig.conf}:

\begin{verbatim}
> java edu.byu.ece.edif.jedif.JEdifNMRSelection myDesign.jedif -c myDesign.cdesc \
  -r myDesign.rdesc --replication_type triplication --nmr_inports --nmr_outports \
  --nmr_c DLL,fdc,clk_buf --nmr_i clk,fifo_output --no_nmr_p clk_port,data_in \
  --no_nmr_c bufg --no_nmr_i mux2,and24 --no_nmr_feed_forward --input_addition_type 1 \
  --output_addition_type 2 --merge_factor 0.85 --optimization_factor 0.90 \
  --part XCV1000-5-BG560 --log myLogFile.log --write_config myConfig.conf
\end{verbatim}

The previous command creates the following output, stored in 
\texttt{myConfig.conf}:

\begin{verbatim}
#myConfig.conf, created by JEdifNMRSelection
#Tue May 12 14:44:30 MDT 2009
no_nmr_i=mux2,and24
write_config=myConfig.conf
merge_factor=0.85
no_nmr_c=bufg
nmr_i=clk,fifo_output
no_nmr_feed_forward=true
replication_type=triplication
log=myLogFile.log
nmr_inports=true
nmr_c=DLL,fdc,clk_buf
input=myDesign.jedif
c_desc=myDesign.cdesc
optimization_factor=0.9
rep_desc=myDesign.rdesc
part=XCV1000-5-BG560
input_addition_type=1
nmr_outports=true
no_nmr_p=clk_port,data_in
output_addition_type=2
\end{verbatim}

Configuration files are defined by the \texttt{java.util.Properties} class. 
However, the format is simple enough that configuration files can easily be 
created by hand or by other programs. As seen above, the format is simply 
\texttt{key=value}. A hash mark (pound sign) (\texttt{\#}) at the beginning of 
a line marks that line as a comment. BL-TMR options are given just as they would 
be on the command-line, with the exception that command-line options with no 
arguments (e.g. \texttt{--nmr\_inports} and \texttt{--do\_scc\_decomposition},
etc.) are specified as either \texttt{true} or \texttt{false}, as seen above.

\subsubsection{Use a Configuration File}

The following example shows how to load \texttt{myConfig.conf} as a configuration
file:

\begin{verbatim}
> java edu.byu.ece.edif.jedif.JEdifNMRSelection --use_config myConfig.conf
\end{verbatim}

\subsubsection{Combining Configuration Files and Command-line Arguments}
Configuration files provide default values of BL-TMR options. Any options 
specified on the command-line will take precedence. (See section 
\ref{useConfig}, ``\texttt{--use\_config}'' for detailed precedence
information.) The following example uses the same options specified by
myConfig.conf, but changes the input and output files:

\begin{verbatim}
> java edu.byu.ece.edif.jedif.JEdifNMRSelection myOtherDesign.jedif \
  -c myOtherDesign.cdesc -r myOtherDesign.rdesc --useconfig myConfig.conf
\end{verbatim}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
